<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Multi-object trackers in Python &mdash; Multi-object trackers in Python 1.0.0 documentation</title>
      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/jquery.js"></script>
        <script src="../_static/underscore.js"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script src="../_static/doctools.js"></script>
        <script src="../_static/sphinx_highlight.js"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Tracker" href="apidocuments.html" />
    <link rel="prev" title="Welcome to Multi-object trackers in Python’s documentation!" href="../index.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
            <a href="../index.html" class="icon icon-home"> Multi-object trackers in Python
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Multi-object trackers in Python</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#available-multi-object-trackers">Available Multi Object Trackers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#available-opencv-based-object-detectors">Available OpenCV-based object detectors:</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#how-to-use-examples">How to use?: Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pretrained-object-detection-models">Pretrained object detection models</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#notes">Notes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#references-credits-and-contributions">References, Credits and Contributions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#citation">Citation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#example-tf-mobilenetssd-centroidtracker">Example: <cite>TF-MobileNetSSD + CentroidTracker</cite></a></li>
<li class="toctree-l1"><a class="reference internal" href="#example-yolov3-centroidtracker">Example: <cite>YOLOv3 + CentroidTracker</cite></a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html">Tracker</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#sort">SORT</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#iou-tracker">IOU Tracker</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#kalman-filter-based-centroid-tracker">Kalman Filter based Centroid Tracker</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#tracks">Tracks</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#kalman-filters">Kalman Filters</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#object-detection">Object Detection</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#utilities">Utilities</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#references-and-credits">References and Credits</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidocuments.html#contributor-covenant-code-of-conduct">Contributor Covenant Code of Conduct</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">Multi-object trackers in Python</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
      <li>Multi-object trackers in Python</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/includeme/readmefile.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="multi-object-trackers-in-python">
<h1>Multi-object trackers in Python<a class="headerlink" href="#multi-object-trackers-in-python" title="Permalink to this heading"></a></h1>
<p>Easy to use implementation of various multi-object tracking algorithms.</p>
<a class="reference external image-reference" href="https://zenodo.org/badge/latestdoi/148338463"><img alt="DOI" src="https://zenodo.org/badge/148338463.svg" /></a>
<p><span class="raw-html-m2r"><br></span></p>
<a class="reference external image-reference" href="https://github.com/adipandas/multi-object-tracker/actions/workflows/python-publish.yml"><img alt="Upload motrackers to PyPI" src="https://github.com/adipandas/multi-object-tracker/actions/workflows/python-publish.yml/badge.svg" /></a>
<section id="available-multi-object-trackers">
<h2>Available Multi Object Trackers<a class="headerlink" href="#available-multi-object-trackers" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>CentroidTracker</p></li>
<li><p>IOUTracker</p></li>
<li><p>CentroidKF_Tracker</p></li>
<li><p>SORT</p></li>
</ul>
</section>
<section id="available-opencv-based-object-detectors">
<h2>Available OpenCV-based object detectors:<a class="headerlink" href="#available-opencv-based-object-detectors" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>detector.TF_SSDMobileNetV2</p></li>
<li><p>detector.Caffe_SSDMobileNet</p></li>
<li><p>detector.YOLOv3</p></li>
</ul>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this heading"></a></h2>
<p>Pip install for OpenCV (version 3.4.3 or later) is available <a class="reference external" href="https://pypi.org/project/opencv-python/">here</a> and can be done with the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">motrackers</span>
</pre></div>
</div>
<p>Additionally, you can install the package through GitHub instead:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">adipandas</span><span class="o">/</span><span class="n">multi</span><span class="o">-</span><span class="nb">object</span><span class="o">-</span><span class="n">tracker</span>
<span class="n">cd</span> <span class="n">multi</span><span class="o">-</span><span class="nb">object</span><span class="o">-</span><span class="n">tracker</span>
<span class="n">pip</span> <span class="n">install</span> <span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="o">.</span>
</pre></div>
</div>
<p><strong>Note - for using neural network models with GPU</strong><span class="raw-html-m2r"><br></span>
For using the opencv <code class="docutils literal notranslate"><span class="pre">dnn</span></code>-based object detection modules provided in this repository with GPU, you may have to compile a CUDA enabled version of OpenCV from source.</p>
<ul class="simple">
<li><p>To build opencv from source, refer the following links:
[<a class="reference external" href="https://docs.opencv.org/master/df/d65/tutorial_table_of_content_introduction.html">link-1</a>],
[<a class="reference external" href="https://www.pyimagesearch.com/2020/02/03/how-to-use-opencvs-dnn-module-with-nvidia-gpus-cuda-and-cudnn/">link-2</a>]</p></li>
</ul>
</section>
<section id="how-to-use-examples">
<h2>How to use?: Examples<a class="headerlink" href="#how-to-use-examples" title="Permalink to this heading"></a></h2>
<p>The interface for each tracker is simple and similar. Please refer the example template below.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">motrackers</span> <span class="kn">import</span> <span class="n">CentroidTracker</span> <span class="c1"># or IOUTracker, CentroidKF_Tracker, SORT</span>
<span class="n">input_data</span> <span class="o">=</span> <span class="o">...</span>
<span class="n">detector</span> <span class="o">=</span> <span class="o">...</span>
<span class="n">tracker</span> <span class="o">=</span> <span class="n">CentroidTracker</span><span class="p">(</span><span class="o">...</span><span class="p">)</span> <span class="c1"># or IOUTracker(...), CentroidKF_Tracker(...), SORT(...)</span>
<span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
    <span class="n">done</span><span class="p">,</span> <span class="n">image</span> <span class="o">=</span> <span class="o">&lt;</span><span class="n">read</span><span class="p">(</span><span class="n">input_data</span><span class="p">)</span><span class="o">&gt;</span>
    <span class="k">if</span> <span class="n">done</span><span class="p">:</span>
        <span class="k">break</span>
    <span class="n">detection_bboxes</span><span class="p">,</span> <span class="n">detection_confidences</span><span class="p">,</span> <span class="n">detection_class_ids</span> <span class="o">=</span> <span class="n">detector</span><span class="o">.</span><span class="n">detect</span><span class="p">(</span><span class="n">image</span><span class="p">)</span>
    <span class="c1"># NOTE:</span>
    <span class="c1"># * `detection_bboxes` are numpy.ndarray of shape (n, 4) with each row containing (bb_left, bb_top, bb_width, bb_height)</span>
    <span class="c1"># * `detection_confidences` are numpy.ndarray of shape (n,);</span>
    <span class="c1"># * `detection_class_ids` are numpy.ndarray of shape (n,).</span>
    <span class="n">output_tracks</span> <span class="o">=</span> <span class="n">tracker</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">detection_bboxes</span><span class="p">,</span> <span class="n">detection_confidences</span><span class="p">,</span> <span class="n">detection_class_ids</span><span class="p">)</span>
    <span class="c1"># `output_tracks` is a list with each element containing tuple of</span>
    <span class="c1"># (&lt;frame&gt;, &lt;id&gt;, &lt;bb_left&gt;, &lt;bb_top&gt;, &lt;bb_width&gt;, &lt;bb_height&gt;, &lt;conf&gt;, &lt;x&gt;, &lt;y&gt;, &lt;z&gt;)</span>
    <span class="k">for</span> <span class="n">track</span> <span class="ow">in</span> <span class="n">output_tracks</span><span class="p">:</span>
        <span class="n">frame</span><span class="p">,</span> <span class="nb">id</span><span class="p">,</span> <span class="n">bb_left</span><span class="p">,</span> <span class="n">bb_top</span><span class="p">,</span> <span class="n">bb_width</span><span class="p">,</span> <span class="n">bb_height</span><span class="p">,</span> <span class="n">confidence</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span> <span class="o">=</span> <span class="n">track</span>
        <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">track</span><span class="p">)</span> <span class="o">==</span> <span class="mi">10</span>
        <span class="nb">print</span><span class="p">(</span><span class="n">track</span><span class="p">)</span>
</pre></div>
</div>
<p>Please refer <a class="reference external" href="https://github.com/adipandas/multi-object-tracker/tree/master/examples">examples</a> folder of this repository for more details. You can clone and run the examples.</p>
</section>
<section id="pretrained-object-detection-models">
<h2>Pretrained object detection models<a class="headerlink" href="#pretrained-object-detection-models" title="Permalink to this heading"></a></h2>
<p>You will have to download the pretrained weights for the neural-network models.
The shell scripts for downloading these are provided <a class="reference external" href="https://github.com/adipandas/multi-object-tracker/tree/master/examples/pretrained_models">here</a> below respective folders.
Please refer <a class="reference external" href="https://github.com/adipandas/multi-object-tracker/blob/master/DOWNLOAD_WEIGHTS.md">DOWNLOAD_WEIGHTS.md</a> for more details.</p>
<section id="notes">
<h3>Notes<a class="headerlink" href="#notes" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p>There are some variations in implementations as compared to what appeared in papers of <code class="docutils literal notranslate"><span class="pre">SORT</span></code> and <code class="docutils literal notranslate"><span class="pre">IoU</span> <span class="pre">Tracker</span></code>.</p></li>
<li><p>In case you find any bugs in the algorithm, I will be happy to accept your pull request or you can create an issue to point it out.</p></li>
</ul>
</section>
</section>
<section id="references-credits-and-contributions">
<h2>References, Credits and Contributions<a class="headerlink" href="#references-credits-and-contributions" title="Permalink to this heading"></a></h2>
<p>Please see <a class="reference external" href="https://github.com/adipandas/multi-object-tracker/blob/master/docs/readme/REFERENCES.md">REFERENCES.md</a> and <a class="reference external" href="https://github.com/adipandas/multi-object-tracker/blob/master/docs/readme/CONTRIBUTING.md">CONTRIBUTING.md</a>.</p>
</section>
<section id="citation">
<h2>Citation<a class="headerlink" href="#citation" title="Permalink to this heading"></a></h2>
<p>If you use this repository in your work, please consider citing it with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@misc</span><span class="p">{</span><span class="n">multiobjtracker_amd2018</span><span class="p">,</span>
  <span class="n">author</span> <span class="o">=</span> <span class="p">{</span><span class="n">Deshpande</span><span class="p">,</span> <span class="n">Aditya</span> <span class="n">M</span><span class="o">.</span><span class="p">},</span>
  <span class="n">title</span> <span class="o">=</span> <span class="p">{</span><span class="n">Multi</span><span class="o">-</span><span class="nb">object</span> <span class="n">trackers</span> <span class="ow">in</span> <span class="n">Python</span><span class="p">},</span>
  <span class="n">year</span> <span class="o">=</span> <span class="p">{</span><span class="mi">2020</span><span class="p">},</span>
  <span class="n">publisher</span> <span class="o">=</span> <span class="p">{</span><span class="n">GitHub</span><span class="p">},</span>
  <span class="n">journal</span> <span class="o">=</span> <span class="p">{</span><span class="n">GitHub</span> <span class="n">repository</span><span class="p">},</span>
  <span class="n">howpublished</span> <span class="o">=</span> <span class="p">{</span>\<span class="n">url</span><span class="p">{</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">adipandas</span><span class="o">/</span><span class="n">multi</span><span class="o">-</span><span class="nb">object</span><span class="o">-</span><span class="n">tracker</span><span class="p">}},</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
</section>
<section id="example-tf-mobilenetssd-centroidtracker">
<h1>Example: <cite>TF-MobileNetSSD + CentroidTracker</cite><a class="headerlink" href="#example-tf-mobilenetssd-centroidtracker" title="Permalink to this heading"></a></h1>
<a class="reference external image-reference" href="https://flic.kr/p/26WeEWy"><img alt="Cows with tf-SSD" class="with-shadow" src="../_images/cows.gif" style="width: 600px;" /></a>
</section>
<section id="example-yolov3-centroidtracker">
<h1>Example: <cite>YOLOv3 + CentroidTracker</cite><a class="headerlink" href="#example-yolov3-centroidtracker" title="Permalink to this heading"></a></h1>
<a class="reference external image-reference" href="https://flic.kr/p/L6qyxj"><img alt="Cars with YOLO" class="with-shadow" src="../_images/cars.gif" style="width: 600px;" /></a>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="../index.html" class="btn btn-neutral float-left" title="Welcome to Multi-object trackers in Python’s documentation!" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="apidocuments.html" class="btn btn-neutral float-right" title="Tracker" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2021, Aditya M. Deshpande.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>